﻿<!DOCTYPE html>
<html>
<head>
    <title>Lava Documentation</title>
        <link href='http://fonts.googleapis.com/css?family=Carrois+Gothic' rel='stylesheet' type='text/css'>
    <link href='http://fonts.googleapis.com/css?family=Inconsolata' rel='stylesheet' type='text/css'>
    <link href='../css/demos.css' rel='stylesheet' type='text/css'>
    <link href="../css/prettify.css" rel="stylesheet" />
</head>
<body>
    <div class="content">
        <div class="page-header">
            <h1>Lava Documentation</h1>
            Lava is an open source javascript framework that allows you to build responsive web applications very quickly, while 
            adhering to MVC best practices.  Lava is compact, powerful and flexible.  Not only does it give you awesome features 
            like data binding, templates and routing, it also gives your application structure.
        </div>
        <div class="clear-10"></div>
        <div class="section-header">
            <h2>Objects (Lava.Object)</h2>
        </div>
        <div class="clear-10"></div>
        <div class="content">
            At the heart of Lava is the object.  An object in lava is a structure with properties and behaviors that can
            be bound to the DOM.  A Lava object is basically a normal javascript object with additional functionality.  
            You define an object by calling Lava.Object() and passing a javascript object as an argument like so:

            <pre class="prettyprint">
var Car = Lava.Object({
    make: 'Ford',
    model: 'Mustang',
    year: 2013             
});
            </pre>

            Now, to create other instances of the Car object, you simply call the clone() method.

            <pre class="prettyprint">
var myCar = Car.clone();
            </pre>

            The myCar object now has all of the properties, values, and behavior that the Car object contains.  You can also pass 
            additional properties to the new object, or even overwrite existing properties.

            <pre class="prettyprint">
var myCar = Car.clone({
    color: 'blue',
    year: 2011                
});
            </pre>

            Adding additional properties or behavior to an existing Lava object is made trivial through the use of the extend()
            method.

            <pre class="prettyprint">
myCar.extend({
    color: 'blue'               
});
            </pre>

            Along with properties, Lava objects can contain behaviors.  For example, let's say that we needed a way to obtain 
            a summary of information about the car.  This can be done easily by adding a method to the object to return a summary.

            <pre class="prettyprint">
myCar.extend({
    summary: function () {
        return myCar.make + ' - ' + myCar.model + ' - ' + myCar.year + ' - ' + myCar.color;      
    }      
});
            </pre>

            Setting or getting properties on an object works exactly how you would expect.

            <pre class="prettyprint">
// set a property
myCar.color = 'red';

// get a property
var make = myCar.make;
var summary = myCar.summary();
            </pre>
        </div>

        <div class="clear-10"></div>
        <div class="section-header">
            <h2>Controllers (Lava.Controller)</h2>
        </div>
        <div class="clear-10"></div>
        <div class="content">
            A Controller is similar to a Lava Object.  One difference is that a controller is meant to be singular.  You cannot clone a controller.  
            Controllers in Lava are used to add behavior to the web application.  They serve as the glue between the model (Lava.Object) and the 
            view (the DOM).  Creating a Controller is identical to creating an Object.
            <pre class="prettyprint">
var PersonController = Lava.Controller({
    getPeople: function () { 
        ... 
    },
    addPerson: function (e, args) {
        ...
    },
    deletePerson: function (e, args) {
        ...
    }
});
            </pre>

            Extending a Controller is identical to extending an Object.
            <pre class="prettyprint">
PersonController.extend({
    getCount: function () {
        ...
    }
});
            </pre>
        </div>

        <div class="clear-10"></div>
        <div class="section-header">
            <h2>Computed Properties (Lava.Computed)</h2>
        </div>
        <div class="clear-10"></div>
        <div class="content">
            Computed Properties in Lava make it possible to create a property on an object whose value is dependent on other properties. Each time a dependent property changes, the computed property will change as well.
            <br><br>
            A simple example of a computed property is the following, in which we compute the full name using two properties.
            <pre class="prettyprint">
var Person = Lava.Object({
    firstName: 'Terry',
    lastName: 'Phillips',
    fullName: Lava.Computed(function () {
        return this.firstName + ' ' + this.lastName;
    })             
});
            </pre>

            Accessing the computed property is a bit different than a normal property. To do so, you use the get() method on the property.
            <pre class="prettyprint">
var fullName = Person.fullName.get();
            </pre>

            Anytime the first or last properties change, it will update any bindings tied to the fullName property.  As you can see, there is no need to 
            specify which dependencies to watch for the computed property.  Lava can determine which properties the computed property is dependent on
            automatically, in most cases.  If you have a complex dependency, or just want to make certain properties dependencies, Lava allows you to manually 
            declare the dependencies like so:
            <pre class="prettyprint">
var Person = Lava.Object({
    firstName: 'Terry',
    lastName: 'Phillips',
    fullName: Lava.Computed('Person.firstName', function () {
        return this.firstName + ' ' + this.lastName;
    })             
});
            </pre>

        </div>

        <div class="clear-10"></div>
        <div class="section-header">
            <h2>Arrays</h2>
        </div>
        <div class="clear-10"></div>
        <div class="content">
            In Lava, arrays are added to objects just as other scalar properties are, but when you add an array
            property to an object, additional functionality is given to the array to support binding.  Unlike other
            data binding frameworks, there is no messy sntax with Lava arrays.  Let's look at a simple example of 
            adding an array property to an Object.

            <pre class="prettyprint">
var Person = Lava.Object({
    contacts: []            
});
            </pre>

            Yes, it's that simple!  To manipulate the array, there are intuitive methods like add(), addAt(), remove(),
            and removeAt().
            
            <pre class="prettyprint">
// Let's assume that Contact is a valid Lava Object
// example of add()
Person.contacts.add(Contact.clone());

// example of addAt().  We will add an Object at index 0.
Person.contacts.addAt(0, Contact.clone());

// example of remove()
Person.contacts.remove(myContact);

// example of removeAt().  We will remove the Object at index 0.
Person.contacts.removeAt(0);
            </pre> 
        </div>
        <div class="clear-10"></div>
        <div class="section-header">
            <h2>Binding & Templates</h2>
        </div>
        <div class="clear-10"></div>
        <div class="content">
            One of the most powerful features available in Lava is Binding.  Lava allows you to bind object properties 
            directly to the UI, easily and efficiently.  The nice part about lava is that there is no additional code 
            required to bind existing DOM elements to Lava Objects.  Bindings are automatically resolved when the document 
            is ready.  It is also just as easy to bind a new set of DOM elements manually at any time.  There are two 
            main ways to bind your objects to the UI, basic bindings and template bindings.<br><br>
            Here is an example of basic bindings using our Person object.

            <pre class="prettyprint">
var Person = Lava.Object({
    firstName: 'Terry',
    lastName: 'Phillips',
    fullName: Lava.Computed('Person.firstName', function () {
        return this.firstName + ' ' + this.lastName;
    })             
});
            </pre>

            Here, we bind the properties of the Person object to separate DOM elements.  
            <pre class="prettyprint">
&lt;input type="text" data-bind="{value: Person.firstName}" /&gt;&lt;br&gt;
&lt;input type="text" data-bind="{value: Person.lastName}" /&gt;&lt;br&gt;
&lt;h2 data-bind="{text: Person.fullName}"&gt;&lt;/h2&gt;
            </pre>

            Let's look at the binding expression on the first input to get an idea of what is going on here.  We use the data-bind attribute
            to tell Lava that we need binding done to this element.  The binding expression uses the same syntax as javascript object literal syntax.  So,
            if you know how to create an object literal, you know how to write Lava binding expressions.  Inside of the data-bind 
            attribute, we specify an object literal with the following format:  {&lt;attribute&gt;: &lt;property path|binding expression object&gt;}.  In this
            case, the attribute that we are binding to is <strong style="font-style:italic">value</strong>, and the property path is <strong style="font-style:italic">Person.firstName</strong>.
            <br><br>
            Let's see the same thing using a template.
            <pre class="prettyprint">
&lt;script type="text/html" id="person-template"&gt;
    &lt;input type="text" data-template="{value: Person.firstName}" /&gt;&lt;br&gt;
    &lt;input type="text" data-template="{value: Person.lastName}" /&gt;&lt;br&gt;
    &lt;h2 data-template="{text: Person.fullName}"&gt;&lt;/h2&gt;
&lt;/script&gt;

&lt;div data-bind="{template: 'person-template'}"&gt;&lt;/div&gt;
            </pre> 

            In the template example, instead of directly binding property values to the DOM elements, we bind a template 
            to a DOM element by using the template binding property and assign it a value equal to the templates id.  
            Inside of the template, we just have the html with the bindings to the properties on the object.  One very
            important thing to remember when using templates is that you must use the data-template attribute when 
            binding as opposed to the data-bind.
        </div>
    </div>
    <script src="../scripts/prettify.js"></script>
    <script type="text/javascript">prettyPrint();</script>
</body>
</html>
